---
title: Deploy your Astro Site to Cloudflare Pages
description: How to deploy your Astro site to the web using Cloudflare Pages.
type: deploy
i18nReady: true
---
import ReadMore from '~/components/ReadMore.astro'

You can deploy your Astro project on [Cloudflare Pages](https://pages.cloudflare.com/), a platform for frontend developers to collaborate and deploy static (JAMstack) and SSR websites.

This guide includes:

- [How to deploy through the Cloudflare Pages Dashboard](#how-to-deploy-a-site-with-git)
- [How to deploy using Wrangler, the Cloudflare CLI](#how-to-deploy-a-site-using-wrangler)
- [How to deploy an SSR site using `@astrojs/cloudflare`](#how-to-deploy-an-ssr-site)

## Prerequisites

To get started, you will need:

- A Cloudflare account. If you don’t already have one, you can create a free Cloudflare account during the process.
- Your app code pushed to a [GitHub](https://github.com/) or a [GitLab](https://about.gitlab.com/) repository.

## How to deploy a site with Git

1. Set up a new project on Cloudflare Pages.
2. Push your code to your git repository (GitHub, GitLab).
3. Log in to the Cloudflare dashboard and select your account in **Account Home** > **Pages**.
4. Select **Create a new Project** and the **Connect Git** option.
5. Select the git project you want to deploy and click **Begin setup**
6. Use the following build settings:

    - **Framework preset**: `Astro`
    - **Build command:** `npm run build`
    - **Build output directory:** `dist`

7. Click the **Save and Deploy** button.

## How to deploy a site using Wrangler

1. Install [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/).
2. Authenticate Wrangler with your Cloudflare account using `wrangler login`.
3. Run your build command.
4. Deploy using `npx wrangler pages deploy dist`.

```bash
# Install Wrangler CLI
npm install -g wrangler
# Login to Cloudflare account from CLI
wrangler login
# Run your build command
npm run build
# Create new deployment
npx wrangler pages deploy dist
```

After your assets are uploaded, Wrangler will give you a preview URL to inspect your site. When you log into the Cloudflare Pages dashboard, you will see your new project.

### Enabling Preview locally with Wrangler

For the preview to work, you must install `wrangler`

```bash
pnpm add wrangler --save-dev
```

It's then possible to update the preview script to run `wrangler` instead of Astro’s built-in preview command:


```json title="package.json"
"preview": "wrangler pages dev ./dist"
```

## How to deploy an SSR site

You can build an Astro SSR site for deployment to Cloudflare Pages using the [`@astrojs/cloudflare` adapter](/en/guides/integrations-guide/cloudflare/).

Follow the steps below to set up the adapter. You can then deploy using either of the approaches documented above.

### Quick install

Add the Cloudflare adapter to enable SSR in your Astro project with the following `astro add` command. This will install the adapter and make the appropriate changes to your `astro.config.mjs` file in one step.

```bash
npx astro add cloudflare
```

### Manual install

If you prefer to install the adapter manually instead, complete the following two steps:

1. Add the `@astrojs/cloudflare` adapter to your project's dependencies using your preferred package manager. If you're using npm or aren't sure, run this in the terminal:

    ```bash
    npm install @astrojs/cloudflare
    ```

2. Add the following to your `astro.config.mjs` file:

    ```js title="astro.config.mjs" ins={2, 5-6}
    import { defineConfig } from 'astro/config';
    import cloudflare from '@astrojs/cloudflare';

    export default defineConfig({
      output: 'server',
      adapter: cloudflare()
    });
    ```

<ReadMore>Read more about [SSR in Astro](/en/guides/server-side-rendering/).</ReadMore>

## Troubleshooting

### Client-side hydration

Client-side hydration may fail as a result of Cloudflare's Auto Minify setting. If you see `Hydration completed but contains mismatches` in the console, make sure to disable Auto Minify under Cloudflare settings.

### Node.js runtime APIs

If you are building a project that is using on-demand rendering with [the Cloudflare SSR adapter](/en/guides/integrations-guide/cloudflare/) and the server fails to build with an error message such as `[Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.`:

- This means that a package or import you are using in the server-side environment is not compatible with the [Cloudflare runtime APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs/). 

- If you are directly importing a Node.js runtime API, please refer to the Astro documentation on Cloudflare's [Node.js compatibility](/en/guides/integrations-guide/cloudflare/#nodejs-compatibility) for further steps on how to resolve this.

- If you are importing a package that imports a Node.js runtime API, check with the author of the package to see if they support the `node:*` import syntax. If they do not, you may need to find an alternative package.
